From 3412f0554f951893170dd4a55f4ee531b057191b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 5 Jun 2020 21:36:27 -0400 Subject: [PATCH] gtk: Documentation fixups Document missing symbols, and other cleanups. --- docs/reference/gtk/gtk4-docs.xml | 1 + docs/reference/gtk/gtk4-sections.txt | 20 +++--- docs/reference/gtk/meson.build | 10 +++ gtk/gtkcolumnviewcolumn.c | 8 +-- gtk/gtkdropdown.c | 9 +-- gtk/gtkmenutrackeritem.c | 4 +- gtk/gtkpaned.c | 94 +++++++++++++++++++++++++--- gtk/gtkstringsorter.c | 1 + gtk/gtktextchild.c | 1 + gtk/gtktextview.c | 8 +++ gtk/gtkwidget.c | 8 +++ gtk/gtkwidget.h | 2 - 12 files changed, 138 insertions(+), 28 deletions(-) diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml index a54bd1a58d..792d3fb0bb 100644 --- a/docs/reference/gtk/gtk4-docs.xml +++ b/docs/reference/gtk/gtk4-docs.xml @@ -121,6 +121,7 @@ + diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt index 8e88c6d1db..ddd8b58de3 100644 --- a/docs/reference/gtk/gtk4-sections.txt +++ b/docs/reference/gtk/gtk4-sections.txt @@ -397,7 +397,6 @@ gtk_single_selection_get_type GtkMultiSeledction GtkMultiSelection gtk_multi_selection_new -gtk_multi_selection_copy gtk_multi_selection_get_type @@ -1455,7 +1454,6 @@ gtk_custom_filter_get_type gtkfilterlistmodel GtkFilterListModel GtkFilterListModel -GtkFilterListModelFilterFunc gtk_filter_list_model_new gtk_filter_list_model_new_for_type gtk_filter_list_model_set_model @@ -2133,12 +2131,18 @@ GtkNotebookPrivate GtkPaned GtkPaned gtk_paned_new -gtk_paned_add1 -gtk_paned_add2 -gtk_paned_pack1 -gtk_paned_pack2 -gtk_paned_get_child1 -gtk_paned_get_child2 +gtk_paned_set_start_child +gtk_paned_get_start_child +gtk_paned_set_end_child +gtk_paned_get_end_child +gtk_paned_set_resize_start_child +gtk_paned_get_resize_start_child +gtk_paned_set_resize_end_child +gtk_paned_get_resize_end_child +gtk_paned_set_shrink_start_child +gtk_paned_get_shrink_start_child +gtk_paned_set_shrink_end_child +gtk_paned_get_shrink_end_child gtk_paned_set_position gtk_paned_get_position gtk_paned_set_wide_handle diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build index 45fc4e5c93..e205261b08 100644 --- a/docs/reference/gtk/meson.build +++ b/docs/reference/gtk/meson.build @@ -13,6 +13,7 @@ private_headers = [ 'gtkappchooserprivate.h', 'gtkapplicationaccelsprivate.h', 'gtkapplicationprivate.h', + 'gtkarrayimplprivate.h', 'gtkbindingsprivate.h', 'gtkbitmaskprivate.h', 'gtkbuilderprivate.h', @@ -148,10 +149,14 @@ private_headers = [ 'gtkmagnifierprivate.h', 'gtkmediafileprivate.h', 'gtkmenubuttonprivate.h', + 'gtkmenusectionboxprivate.h', + 'gtkmenutrackeritemprivate.h', + 'gtkmenutrackerprivate.h', 'gtkmodulesprivate.h', 'gtkmountoperationprivate.h', 'gtknativedialogprivate.h', 'gtknomediafileprivate.h', + 'gtkpango.h', 'gtkplacessidebarprivate.h', 'gtkplacesviewprivate.h', 'gtkplacesviewrowprivate.h', @@ -161,6 +166,7 @@ private_headers = [ 'gtkprintoperation-private.h', 'gtkprivate.h', 'gtkprogresstrackerprivate.h', + 'gtkquery.h', 'gtkrangeprivate.h', 'gtkrbtreeprivate.h', 'gtkrenderbackgroundprivate.h', @@ -170,7 +176,9 @@ private_headers = [ 'gtkroundedboxprivate.h', 'gtkscalerprivate.h', 'gtksearchentryprivate.h', + 'gtkset.h', 'gtksettingsprivate.h', + 'gtkshortcutcontrollerprivate.h', 'gtkshortcutsshortcutprivate.h', 'gtkshortcutswindowprivate.h', 'gtksidebarrowprivate.h', @@ -197,7 +205,9 @@ private_headers = [ 'gtktoolbarprivate.h', 'gtktooltipprivate.h', 'gtktooltipwindowprivate.h', + 'gtktreepopoverprivate.h', 'gtktreeprivate.h', + 'gtktreerbtreeprivate.h', 'gtkutilsprivate.h', 'gtkwidgetpaintableprivate.h', 'gtkwidgetpathprivate.h', diff --git a/gtk/gtkcolumnviewcolumn.c b/gtk/gtkcolumnviewcolumn.c index 8be259f869..708ff6cb5b 100644 --- a/gtk/gtkcolumnviewcolumn.c +++ b/gtk/gtkcolumnviewcolumn.c @@ -831,7 +831,7 @@ gtk_column_view_column_set_visible (GtkColumnViewColumn *self, } /** - * gtk_column_view_get_visible: + * gtk_column_view_column_get_visible: * @self: a #GtkColumnViewColumn * * Returns whether this column is visible. @@ -915,7 +915,7 @@ gtk_column_view_column_set_expand (GtkColumnViewColumn *self, } /** - * gtk_column_view_get_expand: + * gtk_column_view_column_get_expand: * @self: a #GtkColumnViewColumn * * Returns whether this column should expand. @@ -933,7 +933,7 @@ gtk_column_view_column_get_expand (GtkColumnViewColumn *self) /** * gtk_column_view_column_set_resizable: * @self: a #GtkColumnViewColumn - * @resizable: whether this column should be resizable + * @resizable: whether this column should be resizable * * Sets whether this column should be resizable by dragging. */ @@ -952,7 +952,7 @@ gtk_column_view_column_set_resizable (GtkColumnViewColumn *self, } /** - * gtk_column_view_get_resizable: + * gtk_column_view_column_get_resizable: * @self: a #GtkColumnView * * Returns whether this column is resizable. diff --git a/gtk/gtkdropdown.c b/gtk/gtkdropdown.c index c4f3e37f19..4d94d17e2c 100644 --- a/gtk/gtkdropdown.c +++ b/gtk/gtkdropdown.c @@ -839,6 +839,7 @@ gtk_drop_down_set_enable_search (GtkDropDown *self, /** * gtk_drop_down_get_enable_search: + * @self: a #GtkDropDown * * Returns whether search is enabled. * @@ -1014,20 +1015,20 @@ gtk_drop_down_strings_model_new (const char *const *text) /** * gtk_drop_down_set_from_strings: * @self: a #GtkDropDown - * text: a %NULL-terminated string array + * @texts: a %NULL-terminated string array * * Populates @self with the strings in @text, * by creating a suitable model and factory. */ void gtk_drop_down_set_from_strings (GtkDropDown *self, - const char *const *text) + const char *const *texts) { GtkExpression *expression; GListModel *model; g_return_if_fail (GTK_IS_DROP_DOWN (self)); - g_return_if_fail (text != NULL); + g_return_if_fail (texts != NULL); set_default_factory (self); @@ -1035,7 +1036,7 @@ gtk_drop_down_set_from_strings (GtkDropDown *self, gtk_drop_down_set_expression (self, expression); gtk_expression_unref (expression); - model = gtk_drop_down_strings_model_new (text); + model = gtk_drop_down_strings_model_new (texts); gtk_drop_down_set_model (self, model); g_object_unref (model); } diff --git a/gtk/gtkmenutrackeritem.c b/gtk/gtkmenutrackeritem.c index 0dc27598c6..3336d8abd5 100644 --- a/gtk/gtkmenutrackeritem.c +++ b/gtk/gtkmenutrackeritem.c @@ -963,7 +963,7 @@ gtk_menu_tracker_item_request_submenu_shown (GtkMenuTrackerItem *self, gtk_menu_tracker_item_set_submenu_shown (self, shown); } -/** +/* * gtk_menu_tracker_item_get_is_visible: * @self: A #GtkMenuTrackerItem instance * @@ -978,7 +978,7 @@ gtk_menu_tracker_item_get_is_visible (GtkMenuTrackerItem *self) return self->is_visible; } -/** +/* * gtk_menu_tracker_item_may_disappear: * @self: A #GtkMenuTrackerItem instance * diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c index 9a0313c5af..b76a09d564 100644 --- a/gtk/gtkpaned.c +++ b/gtk/gtkpaned.c @@ -109,10 +109,14 @@ * * gtk_widget_set_size_request (hpaned, 200, -1); * - * gtk_paned_pack1 (GTK_PANED (hpaned), frame1, TRUE, FALSE); + * gtk_paned_set_start_child (GTK_PANED (hpaned), frame1); + * gtk_paned_set_start_child_resize (GTK_PANED (hpaned), TRUE); + * gtk_paned_set_start_child_shrink (GTK_PANED (hpaned), FALSE); * gtk_widget_set_size_request (frame1, 50, -1); * - * gtk_paned_pack2 (GTK_PANED (hpaned), frame2, FALSE, FALSE); + * gtk_paned_set_end_child (GTK_PANED (hpaned), frame2); + * gtk_paned_set_end_child_resize (GTK_PANED (hpaned), FALSE); + * gtk_paned_set_end_child_shrink (GTK_PANED (hpaned), FALSE); * gtk_widget_set_size_request (frame2, 50, -1); * ]| */ @@ -1555,6 +1559,13 @@ gtk_paned_new (GtkOrientation orientation) NULL); } +/** + * gtk_paned_set_start_child: + * @paned: a #GtkPaned + * @child: the widget to add + * + * Sets the start child of @paned to @child. + */ void gtk_paned_set_start_child (GtkPaned *paned, GtkWidget *child) @@ -1591,6 +1602,13 @@ gtk_paned_get_start_child (GtkPaned *paned) return paned->start_child; } +/** + * gtk_paned_set_resize_start_child: + * @paned: a #GtkPaned + * @resize: %TRUE to let the start child be resized + * + * Sets the #GtkPaned:resize-start-child property + */ void gtk_paned_set_resize_start_child (GtkPaned *paned, gboolean resize) @@ -1605,6 +1623,14 @@ gtk_paned_set_resize_start_child (GtkPaned *paned, g_object_notify (G_OBJECT (paned), "resize-start-child"); } +/** + * gtk_paned_get_resize_start_child: + * @paned: a #GtkPaned + * + * Returns whether the start child can be resized. + * + * Returns: %TRUE if the start child is resizable + */ gboolean gtk_paned_get_resize_start_child (GtkPaned *paned) { @@ -1613,6 +1639,13 @@ gtk_paned_get_resize_start_child (GtkPaned *paned) return paned->resize_start_child; } +/** + * gtk_paned_set_shrink_start_child: + * @paned: a #GtkPaned + * @resize: %TRUE to let the start child be shrunk + * + * Sets the #GtkPaned:shrink-start-child property + */ void gtk_paned_set_shrink_start_child (GtkPaned *paned, gboolean shrink) @@ -1627,6 +1660,14 @@ gtk_paned_set_shrink_start_child (GtkPaned *paned, g_object_notify (G_OBJECT (paned), "shrink-start-child"); } +/** + * gtk_paned_get_shrink_start_child: + * @paned: a #GtkPaned + * + * Returns whether the start child can be shrunk. + * + * Returns: %TRUE if the start child is shrinkable + */ gboolean gtk_paned_get_shrink_start_child (GtkPaned *paned) { @@ -1636,14 +1677,11 @@ gtk_paned_get_shrink_start_child (GtkPaned *paned) } /** - * gtk_paned_get_end_child: + * gtk_paned_set_end_child: * @paned: a #GtkPaned + * @child: the widget to add * - * Retrieves the end child of the given #GtkPaned. - * - * See also: #GtkPaned:end-child - * - * Returns: (transfer none) (nullable): the end child widget + * Sets the end child of @paned to @child. */ void gtk_paned_set_end_child (GtkPaned *paned, @@ -1663,6 +1701,16 @@ gtk_paned_set_end_child (GtkPaned *paned, g_object_notify (G_OBJECT (paned), "end-child"); } +/** + * gtk_paned_get_end_child: + * @paned: a #GtkPaned + * + * Retrieves the end child of the given #GtkPaned. + * + * See also: #GtkPaned:end-child + * + * Returns: (transfer none) (nullable): the end child widget + */ GtkWidget * gtk_paned_get_end_child (GtkPaned *paned) { @@ -1671,6 +1719,13 @@ gtk_paned_get_end_child (GtkPaned *paned) return paned->end_child; } +/** + * gtk_paned_set_resize_end_child: + * @paned: a #GtkPaned + * @resize: %TRUE to let the end child be resized + * + * Sets the #GtkPaned:resize-end-child property + */ void gtk_paned_set_resize_end_child (GtkPaned *paned, gboolean resize) @@ -1685,6 +1740,14 @@ gtk_paned_set_resize_end_child (GtkPaned *paned, g_object_notify (G_OBJECT (paned), "resize-end-child"); } +/** + * gtk_paned_get_resize_end_child: + * @paned: a #GtkPaned + * + * Returns whether the end child can be resized. + * + * Returns: %TRUE if the end child is resizable + */ gboolean gtk_paned_get_resize_end_child (GtkPaned *paned) { @@ -1693,6 +1756,13 @@ gtk_paned_get_resize_end_child (GtkPaned *paned) return paned->resize_end_child; } +/** + * gtk_paned_set_shrink_end_child: + * @paned: a #GtkPaned + * @resize: %TRUE to let the end child be shrunk + * + * Sets the #GtkPaned:shrink-end-child property + */ void gtk_paned_set_shrink_end_child (GtkPaned *paned, gboolean shrink) @@ -1707,6 +1777,14 @@ gtk_paned_set_shrink_end_child (GtkPaned *paned, g_object_notify (G_OBJECT (paned), "shrink-end-child"); } +/** + * gtk_paned_get_shrink_end_child: + * @paned: a #GtkPaned + * + * Returns whether the end child can be shrunk. + * + * Returns: %TRUE if the end child is shrinkable + */ gboolean gtk_paned_get_shrink_end_child (GtkPaned *paned) { diff --git a/gtk/gtkstringsorter.c b/gtk/gtkstringsorter.c index 8ca9fce725..2879faf140 100644 --- a/gtk/gtkstringsorter.c +++ b/gtk/gtkstringsorter.c @@ -330,6 +330,7 @@ gtk_string_sorter_get_ignore_case (GtkStringSorter *self) /** * gtk_string_sorter_set_ignore_case: * @self: a #GtkStringSorter + * @ignore_case: %TRUE to ignore case differences * * Sets whether the sorter will ignore case differences. */ diff --git a/gtk/gtktextchild.c b/gtk/gtktextchild.c index e5963b9177..f569a503bd 100644 --- a/gtk/gtktextchild.c +++ b/gtk/gtktextchild.c @@ -430,6 +430,7 @@ gtk_text_child_anchor_finalize (GObject *obj) /** * gtk_text_child_anchor_get_widgets: * @anchor: a #GtkTextChildAnchor + * @out_len: (out): return location for the length of the array * * Gets a list of all widgets anchored at this child anchor. * diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c index d186b4941b..13b2010477 100644 --- a/gtk/gtktextview.c +++ b/gtk/gtktextview.c @@ -5737,6 +5737,14 @@ gtk_text_view_snapshot (GtkWidget *widget, } } +/** + * gtk_text_view_remove: + * @text_view: a #GtkTextView + * @child: the child to remove + * + * Removes a child widget from @text_view. + */ + void gtk_text_view_remove (GtkTextView *text_view, GtkWidget *child) diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 960232e942..91ad52e502 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -11846,6 +11846,8 @@ gtk_widget_observe_controllers (GtkWidget *widget) * gtk_widget_get_first_child: * @widget: a #GtkWidget * + * Returns the widgets first child. + * * Returns: (transfer none) (nullable): The widget's first child */ GtkWidget * @@ -11862,6 +11864,8 @@ gtk_widget_get_first_child (GtkWidget *widget) * gtk_widget_get_last_child: * @widget: a #GtkWidget * + * Returns the widgets last child. + * * Returns: (transfer none) (nullable): The widget's last child */ GtkWidget * @@ -11878,6 +11882,8 @@ gtk_widget_get_last_child (GtkWidget *widget) * gtk_widget_get_next_sibling: * @widget: a #GtkWidget * + * Returns the widgets next sibling. + * * Returns: (transfer none) (nullable): The widget's next sibling */ GtkWidget * @@ -11894,6 +11900,8 @@ gtk_widget_get_next_sibling (GtkWidget *widget) * gtk_widget_get_prev_sibling: * @widget: a #GtkWidget * + * Returns the widgets previous sibling. + * * Returns: (transfer none) (nullable): The widget's previous sibling */ GtkWidget * diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h index 48e3665460..06e829d62b 100644 --- a/gtk/gtkwidget.h +++ b/gtk/gtkwidget.h @@ -161,8 +161,6 @@ struct _GtkWidget * @grab_notify: Signal emitted when a widget becomes shadowed by a * GTK+ grab (not a pointer or keyboard grab) on another widget, or * when it becomes unshadowed due to a grab being removed. - * @child_notify: Signal emitted for each child property that has - * changed on an object. * @get_request_mode: This allows a widget to tell its parent container whether * it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or * %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. -- 2.30.2